Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / conch.arc / DOCS.PLN < prev next >

Wrap

Text File | 1980-01-01 | 33.8 KB | 1,011 lines

Conch An Enhanced Command Shell For IBM PCs And Compatibles Running MS-DOS Version 1.00 Written by Richard W. Sellens (c) R.W. Sellens 1985 Trademarks IBM - International Business Machines Corporation MS-DOS - Microsoft, Inc. Unix - AT&T, Bell Labs DeSmet - DeSmet Software This program is shareware. You are encouraged to copy the executable code and documentation and distribute it to others, subject to these simple conditions: - This program and documentation are copyright. The copyright and all other rights to this program remain the property of the author, Richard W. Sellens. - This program and documentation are not to be distributed in modified form. - This program and documentation are not to be distributed for profit. - The author will not be responsible for any damages arising from the use, misuse, or inability to use this program. The essentially unrestricted distribution of this program allows you, the end user, to test the program under your own operating conditions and determine whether or not it is useful to you. If you make regular use of this program I ask that you make a contribution to my continuing software development efforts. Please send $25 license fee to: Richard W. Sellens 372A Churchill Court Waterloo, Ontario Canada N2L 6B4 A receipt will be provided on request. If you find any bugs in the program, or have any suggestions for improvements, please let me know by mail at the above address. Introduction to Conch As anyone who has used MS-DOS must have noticed, the command processor supplied with the operating system is quite simple. People who have used the facilities available on Unix systems must long for a more sophisticated, powerful shell. Those who spend a lot of time interacting with the computer at the command line level could benefit from a more comfortable way to make use of the basic command processor features. Conch does not provide a fully programmable shell, but it does provide many of the comfort features. Command line editing - Conch uses the PC editing keys in just the manner that one would expect. This makes it much easier to enter commands and correct errors. I/O redirection - Conch performs I/O redirection and piping itself, using the same command line format as the DOS shell. History - Conch maintains a buffer of previously entered command lines which can be recalled to the command line, edited, and re-executed. This is done using the vertical cursor motion keys to select the desired command. Command Aliasing - It is often desirable to call a given command sequence by another name. This allows the shortening of long command strings to simple mnemonics as well as the reassignment of the standard command names to names which make more sense to the user. Virtual Device Names - On hard disk systems with complex directory tree structures it can be difficult to remember the exact paths to directories that are in common use. Also, it is painful to type a long path name for every directory reference. Conch allows you to define virtual device names to shorten and simplify command line path references. Conch is written in DeSmet C, and uses only standard MS-DOS function calls, with one exception: IBM PC BIOS interrupt 10 hex is used to access the video screen. The net result is that Conch should run on any machine that makes a half hearted attempt to be compatible with the IBM PC. Starting Conch Two things should be done at the DOS level, perhaps in an autoexec.bat file, before starting Conch: - The command search path should be set to the desired value using the DOS path command. This cannot be changed from within Conch. - The prompt string should be set to the desired value using the DOS prompt command. This cannot be changed from within Conch. Conch is then invoked by typing conch Conch will load, display a banner with the version number and copyright notice and initialize itself. As part of this initialization Conch will look for a file named conchrc in the current directory. Commands will be taken from this file and executed, just as if they had been typed at the command line, but they will not be recorded as history. If the default directory is changed before Conch is invoked, then Conch will take conchrc from the new directory, rather than the root directory. This makes it possible to provide different initialization procedures for different users. A simple start-up program can be used to switch to a user's home directory before Conch is invoked, thus controlling the initialization file used. The Command Line Editor When Conch is started it will perform some initialization and then display the command prompt, just as the DOS shell does. You may then enter a command, just as you would with DOS, using the alpha-numeric keys followed by a carriage return. If your typing is perfect then you will notice no difference. If however, you are prone to error like the rest of us, the following features will make it easy to modify the command as typed so far. Motion - The left and right arrow keys will move the cursor one space left or right, but will move no further left than the first character of the command line and no further right than the first space beyond the end of the current command line. The Home and End keys will move the cursor to the beginning and end of the command line respectively, while the Esc key will move the cursor to the beginning of the command line and erase anything typed so far. Delete - The Del key will delete the current character, unless the cursor is at the end of the line, in which case it has no effect. The backspace key deletes the character immediately to the left of the cursor and moves the remainder of the line in, unless the cursor is at the beginning of the line, in which case it has no effect. Insert - Normally a character typed at the keyboard will overtype the character under the cursor. The Ins key toggles the insert mode on and off. When in insert mode, characters typed at the keyboard are inserted before the current character. When insert mode is on the cursor will appear as a block, rather than the usual underbar. If this sounds familiar, it is because it duplicates the line editing facilities of the BASIC interpreter at the command line. This capability simplifies the entry of commands and makes it easy to edit previous commands called up from the history facility of the shell. In addition to these editing capabilities, there are two key combinations that have a special effect at the command line. Alt-H will cause the current contents of the command line to be added to the history buffer. Alt-P will cause the current contents of the command line to be added to the pending commands list. In neither case will the command be executed, it will just be stored. What Does a Command Line Look Like? The most general form of the command line is: <command group>[;<command group>]... Any number of command groups may be entered on a line, separated by semicolons, subject only to the maximum allowable length of a line. (The DOS imposed maximum is 128 characters.) Each command group will be executed in sequence, just as if they had been entered on succeeding command lines. This feature is an extension of the DOS command processor. Conch will treat any command line which starts with a period (.) as a null line. This is consistent with DOS, and provides a way to include comments in command lists. A command group has the same form as the command line described in the DOS manual. In its simplest form a command group contains only the name of the command to be executed, but it may also contain arguments, pipes, and I/O redirection. <command> [arg...][|<command> [arg...]...][<infile][[>]>outfile] If a pipe (|) is used to join commands, then the data sent to standard output by the first command is fed to the standard input of the second command. Any number of commands may be piped together in this way. See the section titled Pipes and/or the DOS manual for further details. If arguments are found that begin with one of `<', `>', or `>>' the remainder of that argument is used as a source or destination for I/O redirection. `<' indicates a source file or device which is to replace the current standard input device. `>' indicates a destination file or device that is to replace the current standard output device. If the file exists the current contents will be replaced. `>>' is the same as `>', except that the output will be appended to the current contents of the file, if any. See the DOS manual for further details. Commands and arguments are separated by spaces or tabs as delimiters. Spaces are optional around pipes, semicolons, and preceding I/O redirection. Quotes may be used to prevent special characters such as `|', `;', `<', `>', tabs and spaces from being interpreted by the shell. See the section titled Parsing of the Command Line for details. Command History Mechanism Conch automatically saves each command typed at the keyboard in a buffer for future reference. When the buffer fills, the oldest commands are discarded to make room for new ones. The number of commands that are available is dependent on the size of the buffer, buffer utilization by the other features of Conch, and the lengths of the commands that were saved. Generally the buffer will hold more history than you need, but if the amount saved is insufficient it will be necessary to move up to a version of the shell that was created with a larger buffer. When Conch gives you the command prompt you may enter a command using the editing keys as described in the Command Line Editor section, or you may select a previously typed command from the history buffer. While on the command line, the up and down arrow keys will move you through the history buffer, displaying a previously entered command on the current command line. The up arrow moves backward in time, while the down arrow will move you forward. The buffer does not wrap, so that eventually you will reach the oldest available command entry and go no further. Additionally, if the PgUp key is pressed while on the command line, it will provide a display of a page of the history buffer so that commands appear in context. Each line of the display will contain an old command, or just the first part of the command if the complete command would have run off the screen. An indicator points out the currently selected line of history and, as before, the selected history line will appear in its entirety on the current command line. In this display mode the up and down arrow keys will still move through the history buffer one command at a time, while the PgUp and PgDn keys will move up or down in larger increments. Once the desired command has been selected it may be executed as is, simply by pressing carriage return, or it may be edited just as if the text of the command had been entered from the keyboard. Any modifications made to the text on the command line will have no effect on the image of the old command stored in the history buffer. Also, when you re-execute the command it will be stored in the history buffer again, whether or not it was modified. In addition to the history buffer, Conch maintains a pending commands buffer. Commands are added to the buffer by using Alt-P to store the current command line, or by reading them in using the -r option of the pending command. The pending command also allows you to display the contents of the buffer, execute the commands in the buffer, write them to a file, or flush the buffer. See the command summary for details. Command Aliasing Conch maintains a list of command aliases which are input by the user. A command alias is essentially a statement that ``When I say this, I really mean that.''. An alias is added to the shell's list by using the alias command. alias <name> <replacement string> <name> is the name that you will use to request a particular action and <replacement string> is the command line to be used to produce that action. For example alias dir ls -l tells Conch that each time you enter the command dir, it should execute the command ls -l. This can be extremely useful, especially for the more complex commands. <name> must be a string of less than 64 characters containing only the letters A through Z, the digits 0 through 9 and the characters $ # & @ ! % ( ) - { } _ All alias names are converted to lower case for storage, making Conch case independent just like DOS. If the previously aliased <name> is followed by arguments on the command line they are usually just transferred to the end of the <replacement string>, and separated from it by whitespace. The command entry dir \temp\idea would be translated into ls -l \temp\idea for execution. The exception comes when <replacement string> contains one or more occurrences of the tail substitution character. (The tail substitution character is initially set as `$' but it can be changed to any other character using the tsub command.) If the tail substitution character occurs in the replacement string, in each instance it will be replaced with the command tail. The command tail will be stripped of leading and trailing whitespace so that if this alias is set, alias killer "del file$.bak ; del dud$.*" (Note that quotes are required around the replacement string to prevent Conch from interpreting the semicolon before it is sent to the alias command.) killer 1 will be expanded to del file1.bak ; del dud1.* and killer test will be expanded to del filetest.bak ; del dudtest.* If the alias command is issued with a name which is already aliased, then the new alias definition will replace the old. No warning or diagnostic message will be issued. If an alias is to be removed, rather than redefined, the unalias command is used. It takes the form: unalias <name> where <name> is the name of a previously defined alias. The aliasing mechanism is fully recursive, so aliases may be defined in terms of other aliases. There is a check on the recursion to prevent either direct, or indirect circular recursion. alias ls ls -l will result in one substitution, giving ls -l whenever ls is entered. alias ls dir -l alias dir ls will result in two substitutions, giving ls -l whenever ls is entered. Virtual Device Names When tree structured directories grow, the paths to the directories can become long, and perhaps hard to remember. The use of virtual device names makes it easier to remember the names of commonly used directories, as well as easing the typing load. A virtual device is defined by the vdev command vdev <name> <replacement string> and can be redefined by issuing another vdev command for the same name. <name> must be at least 2 characters long, so as not to conflict with the single letter disk drive identifiers. For example, the text of my thesis might be stored in a directory named c:\rick\school\thesis\. A virtual device could be created by vdev thesis c:\rick\school\thesis\ Any time the characters thesis: appear at the start of a token they will be replaced by the replacement string; in this case c:\rick\school\thesis\. Thus type thesis:chap1 will be expanded to type c:\rick\school\thesis\chap1 In the special case where the name and colon form the entire token, any trailing backslash will be removed, so that cd thesis: will be expanded to cd c:\rick\school\thesis just the way it should be. Also, simply declaring a virtual device name on the command line will take you to the directory it represents. This is analogous to using a: to move to drive A. This means that thesis: is almost equivalent to cd thesis: The difference is that cd thesis: will change the default directory of drive C to \rick\school\thesis without changing the default drive, while thesis: will also change the default drive to ``take you there''. On machines with a single hard disk, where the default drive is likely to remain constant, the two are interchangeable. The virtual device name facility is fully recursive, so virtual device names may be defined in terms of other virtual device names. vdev old thesis:old\ will set up old: to be expanded into c:\rick\school\thesis\old\. Any circular reference, where a virtual device name is defined in terms of itself, will cause an error. To complement the virtual device naming capability, Conch keeps a list of reserved device names. The rdev command is used to add a device name to the list. rdev <name> The vdev command will generate an error if the user tries to create a virtual device with the same name as a previously defined reserved device. This is the only purpose of the reserved device name facility. The rules given for legal characters in alias names also apply to both vdev and rdev names. They are also stored in lower case, making them case independent. Summary of Conch Internal Commands This section lists all of the Conch internal commands, and provides the mechanical details of their use. For further information, and examples of the more complex commands, see the narrative sections of the manual. alias [<name> <replacement string>] Instructs the shell to substitute a replacement string for the command <name> in future. If <replacement string> contains special characters like `|', `;', `>', `<, etc., enclose the string in either single ('') or double ("") quotes to prevent their evaluation before substitution. If no arguments are given, the current list of aliases is printed. cd [d:][<path>] Behaves just like the DOS cd, except that <path> may include a virtual device name. exit Leaves Conch and returns to DOS. history [-n [<filename>]] Prints out the complete history buffer, in the order in which the commands were entered. If an argument is included the results will be: -f the history buffer is flushed, eliminating all previous entries. -w[n] <filename> writes the most recent n commands from the contents of the history buffer to <filename>. -r <filename> reads in command lines from <filename> and adds them to the history buffer. pending [-n [<filename>]] Prints out the list of pending commands if no arguments are given. If arguments are included the results will be: -e the pending commands are executed. They will not be recorded as history, since they were not entered from the command line. -f the pending command list is flushed, eliminating all previous entries. -w <filename> writes the contents of the pending command list to <filename>. -r <filename> reads in command lines from <filename> and appends them to the pending command list. rdev [<name>] Adds <name> to the reserved device name list. If no argument is given, a list of the defined reserved device names is printed. source <filename> Takes command input from a file, rather than the keyboard. This provides the most rudimentary of batch facilities. The commands in <filename> will not be recorded as history, since they were not entered from the command line. tsub [<char>] Sets the tail substitution character to the first non-blank character after tsub. If there is no argument, the current tail substitution character is displayed. unalias <name> Removes the alias entry, if any, for <name>. vdev [<name> <replacement string>] Adds <name> to the virtual device name list, so that in future name: at the beginning of a token will be replaced with <replacement string>. If no arguments are given, the current virtual device name list will be printed. Parsing of the Command Line To interpret the Conch command line it is necessary to take it apart, massage it a bit, and reassemble it. This is called parsing and processing. For the most part Conch parsing is very simple; a command is composed of tokens which are separated by whitespace. (Whitespace is the generic term for characters such as spaces or tabs, appearing singly or in a group.) When the command is processed the tokens are separated, and the whitespace between the tokens is thrown away. After the tokens are processed, they are reassembled into a command with new whitespace between them. This will have no effect on the execution of the command, unless the exact configuration of the whitespace was important. Conch will not preserve bizarre combinations of whitespace between tokens. Thus, if your application is sensitive to the configuration of whitespace, special measures may be needed. After the command line is broken into tokens, it is checked for semicolons. If any are found the line is broken into separate command groups which are sequentially fed back into the top of the processor. Then any I/O redirection is stripped out. (Conch is not sensitive to the position of I/O redirection tokens in the command group.) If a command group contains pipes it is broken into separate commands, with appropriate redirection to temporary files, and fed back into the top of the processor. Once it is dealing with a single command the processor tests the first word for alias substitution. If a substitution results in multiple commands (using either semicolons or pipes) the command group is fed back into the top of the processor. The processor then tests each token to see if it begins with a recognized virtual device name, and if so, makes the necessary substitution. Any I/O redirection required is set up. Any quotes within the command string are removed, unless they are preceded by a backslash (\), in which case the backslash is removed. If the command is one of the internal commands the appropriate function is called. Otherwise, Conch looks in the current directory and down the search path for the named command as either a .com, .exe, or .bat file. If found, it is executed and passed a tail composed of all the remaining tokens, separated by spaces. The tail will also have one leading space, so that it will appear to the application that it was invoked from the DOS command line with exactly one space between the command name and the arguments. Some badly written programs process the command tail based on the assumption that it has exactly one leading space. Quotation Marks Single ('') and double ("") quote pairs can be used to keep the parser from messing with portions of the command line. Anything within single or double quotes will be untouched by the parser. The quotes will be removed before the command tail is passed to the command itself. This is useful for maintaining peculiar whitespace combinations, and for slipping normally significant characters past the command processor. The command grep " ;" will result in grep being invoked and passed a command tail composed of two spaces and a semicolon. (The first space is the one separating the command and the tail, while the second comes from within the quoted string.) If the quotes were not present, Conch would interpret the semicolon as a command separator, and would ignore the superfluous space. The result would be the same if single quotes ('') had been used, rather than double quotes. The next question is ``How do you include quotes on the command line as characters, rather than delimiters?''. To include quotes as characters they must be preceded by a backslash (\). For example grep \'"\" ;" would invoke grep, and pass it a command tail made up of a space, a single quote, a double quote, a space and a semicolon. Pipes Since DOS is not multi-tasking, it is not possible to implement ``true'' pipes. The technique used by Conch is the same as that used by command.com. Piped commands are converted into a sequentially executed series of commands with I/O redirection through temporary files. Under Conch these files have names of the form temp:%pipexx where xx is a two letter combination that varies to differentiate between files, and temp: is a virtual device name which must be defined by the user before piping is used. If a RAM disk is being used, setting temp: to represent a directory on the RAM disk will result in much faster execution of piped commands. Conch ensures that the xx in the pipe filenames are different for each file created, but if multiple copies of Conch are active, then the pipe filenames will not be unique. This will cause problems if commands containing pipes are piped into a second copy of Conch. For example, the command: dummy | conch | cat will not behave properly if dummy feeds piped commands to conch, because the pipefile names will conflict. This is a bug, but one that is unlikely to cause significant inconvenience, or even be evident to most users. Command.com and MS-DOS Internal Commands Conch installs itself on top of command.com, and uses some of the features provided by command.com, such as the 4B hex function call for executing a program. This is not as much of penalty as might be expected. Only the resident portion of command.com is retained, and its size is only a couple of Kbytes. Conch does not provide most of the internal commands that exist in command.com. These commands are not lost to the user. They can still be run by invoking command.com with the /c option; i.e., command /c dir This is extremely bulky, but the internal commands can be aliased. alias dir command /c dir will make dir behave just the way it does when issued at the DOS command line. Invoking command.com to perform DOS tasks takes a little longer. On my PC with a 10 Mbyte hard drive it takes about three quarters of a second longer to start the task. In my opinion, this delay is not particularly noticeable, as the commonly used DOS internal commands are I/O bound anyway, so the response is never instantaneous. Using command.com to perform program loading and internal commands allows for complete compatibility with a bare DOS system, so that you will be hit with a minimum number of surprises. It also means that Conch is independent of DOS version. If a new version of DOS is issued, with an expanded or different command set, just change the aliases. I feel that these advantages outweigh the minor performance disadvantage. It is a quirk of DOS that whenever a new command.com is invoked, it must be the same copy as the machine was booted from. Because of this, the first copy of command.com found down the search path must be the one that you booted from. This will usually mean including c:\ as one of the path elements. Alternatively you could alias command to c:\command, so as to be specific. Batch Files Conch runs batch files by invoking command.com. This means that none of the features of Conch are available inside the batch file. However, when a batch file is run, the command line arguments will be processed by Conch before they are passed to command.com, so virtual device names, etc. may be used on the command line. Commonly used batch files tend to be just lists of commands, without any use of the flow control and other batch file features provided by DOS. Batch files of this type can be replaced by aliasing, if the list of commands is short, or by using the source command if the list of commands is longer. See the sample conchrc for an aliasing example. Error Messages Produced by Conch If Conch detects an error it will print out one of the messages contained in this section. It may also print a line of text to provide a clue concerning the cause of the error, or an explanation. Most error messages produced by Conch are self explanatory. Bad Alias Name. Bad Command Name. Bad Device Name. Bad Filename. Bad Path Name. If Conch says something is ``bad'', then that thing either does not exist, or Conch was unable to find it, or in the case of a device it has already been defined as a reserved device name. Illegal Character in Name -- A-Z, 0-9, $#&@!%()-{}_ Permitted. An attempt was made to define an alias, virtual device name or reserved device name containing characters other than those permitted. Command Too Long When Expanded. DOS restricts commands to a maximum of 128 characters. Conch will not allow you to input a command that is longer than that, however, if subsequent expansion of the command would make it longer than 128 characters this error message is generated. Extra Arguments Supplied to Internal Command. Too many arguments were given when invoking a Conch internal command. Insufficient Pointer Space. No More Space in Main Buffer. Out of Memory. Recursion Too Deep -- Need Larger Memory Version. Any of these errors indicate that you were asking Conch to do something that was too big or too complex for the version of the program installed. This includes things such as defining more aliases, etc. than will fit in the space allotted for the buffer or pointers, or asking Conch to evaluate a complex command group involving many levels of recursion in the definition of aliases or virtual device names. The solution to the problem is to use a larger memory version of the program. On the distribution disk are several sequentially numbered versions of the program. (conch1.exe, conch2.exe, etc.) The higher the number, the larger the amount of working space provided for Conch. Naturally, using a larger memory version of the program will leave less of your machine's memory available to run applications in. Warning -- Unmatched Single or Double Quotes. If Conch finds unmatched quotes it will issue this warning message. It will proceed with the execution of the command, but the entire portion of the line after the last quotation mark will be treated as a single token. The effect will be the same as if a closing quotation mark had been added at the end of the line. Could Not Open File -- Probably Disk Full. Error Writing File -- Probably Disk Full. These two are self explanatory Unspecified error. This message will appear if the program just run terminated with a non-zero exit code. The exit code is mechanism provided by DOS which allows a program to communicate its exit status to the program that invoked it. Usually a non-zero exit code means the program terminated due to some error condition. This message will also be displayed if one of Conch's internal routines returns an unforseen error code. This should not happen. If it does please contact the author with details of how the error occurred, and how it can be repeated. Ordering Information for the Program and Source Code A complete copy of the source code for Conch is available for personal use only. It is written in the DeSmet C language, with some imbedded assembly code. A signed and dated copy of the declaration below must accompany your order. Please send me a copy of the complete source code for Conch. This source code is to be used only by me, or by my agents under my supervision. No portion of the source code, or any executable code produced from it will be distributed to a third party. I understand that this program and documentation are copyright and that the copyright and all other rights to this program remain the property of the author, Richard W. Sellens. I also understand that the author will not be responsible for any damages arising from the use, misuse, or inability to use this program. Name _____________________________ Signature _______________________ Date _______________________ --------------------------------------------------------------------- Order Form -- Conch Shell Program Demo Diskette -- Software and manual text on diskette. _______ copies at $10 each $_____________ Conch Program Package -- Software on diskette complete with hardcopy manual. Includes $25 license fee. _______ copies at $35 each $_____________ Conch Source Package -- Software and source code on diskette complete with hardcopy manual. Includes $25 license fee. A signed and dated copy of the declaration above must be provided for each copy ordered. _______ copies at $50 each $_____________ Total $_____________ Ontario residents add 7% P.S.T. $_____________ Enclosed with this order $_____________ Name: ______________________________________ Address: ______________________________________ ______________________________________ Mail to: R.W. Sellens, 372A Churchill Ct., Waterloo, Ont., Canada N2L 6B4 ___________________________________ Mail to: R.W. Sellens, 372A Churchill Ct.,